home *** CD-ROM | disk | FTP | other *** search
/ CU Amiga Super CD-ROM 21 / CU Amiga Magazine's Super CD-ROM 21 (1998)(EMAP Images)(GB)[!][issue 1998-04].iso / CUCD / Programming / dclistview / dclistview.doc < prev    next >
Text File  |  1998-01-17  |  5KB  |  113 lines
  1. DCListview PLUGIN
  2. -----------------
  3.  
  4.     This plugin creates a GadTools Listview gadget, almost identical to the
  5. standard EasyGUI one, except that it will also report double-clicks on list
  6. items.
  7.  
  8. Usage:
  9.  
  10.     [DCLIST, {actionfunction}, dc, TRUE]
  11.  
  12.     Notes:
  13.     -   Be sure the 'isgt' field of the PLUGIN gadget is always TRUE, since
  14.     this uses a GadTools gadget.
  15.     -   The DCLIST constant (which =PLUGIN) is available to be used in your
  16.     EasyGUI gadget list, as shown above.  This can make plugins in gadget lists
  17.     easier to identify, especially if you use a lot of different plugins.
  18.     -   Your action function will be called (or your action value returned by
  19.     easyguiA()) when:
  20.         -   an item is selected with the mouse, and again on a double click.
  21.         -   the assigned key is pressed, alone or shifted.
  22.         NOTE: if you use an action value instead of an action function, you
  23.         won't hear about double clicks since your GUI will have closed :-)
  24.  
  25. Methods:
  26.  
  27.     dclistview(tags)
  28.  
  29.           The constructor for this plugin, where 'tags' is a PTR TO a list of
  30.         tagitems from those listed below marked [I].  All values default to
  31.         something reasonable, so you can use simply [TAG_DONE] as your list.
  32.           You *must* open 'utility.library' prior to calling this function, or
  33.         it will raise a "util" exception.
  34.           This function has no return value.
  35.  
  36.     set(attr, val)
  37.  
  38.           Sets any attribute to the value given, where 'attr' is any item
  39.         listed below that is marked [S], and 'val' is some reasonable value
  40.         for said attribute.
  41.           This function has no return value, EXCEPT when setting DCLV_CURRENT
  42.         to a new value.  In this case it returns the value that DCLV_CURRENT
  43.         was actually set to, should you have tried to set it to a value that
  44.         was out of range.
  45.  
  46.     value, check:=get(attr)
  47.  
  48.           Gets the value for the specified attribute, where 'attr' is any item
  49.         listed below marked [G].  The second returned value, 'check', is TRUE
  50.         if 'attr' is in fact "getable", otherwise FALSE.
  51.  
  52.     END *must* be called for each NEWed object.
  53.  
  54. Possible attribute tags:
  55.  
  56.     DCLV_LABEL                        [I..]
  57.         The label which appears above the gadget.  Including a "_" in
  58.         this string will automatically assign the next character as the
  59.         keyboard shortcut, and will indicate it as such in the label.
  60.         (Default: No label text)
  61.     DCLV_RELX                         [I..]
  62.         The usual relative gadget width (Default: 5)
  63.     DCLV_RELY                         [I..]
  64.         The usual relative gadget height (Default: 5)
  65.     DCLV_LIST                         [ISG]
  66.         The list to be displayed in the gadget.  Usual gadtools handling
  67.         applies:  set to NIL to remove the list from the gadget, set to -1
  68.         to detach the list without clearing it. (Default: NIL)
  69.     DCLV_CURRENT                      [ISG]
  70.         The list item to be highlighted and placed at the top of the listview.
  71.         This item will also be displayed beneath the listview under v37 or
  72.         with a highlight bar under v39.  This value will always be updated
  73.         when the user selects a list item.
  74.     **  NOTE: If you don't want ANY list item highlighted initally, set
  75.         this tag to -1 (Default).  NOTE FURTHER, though, that the value of
  76.         this attribute will NOT change if the user does not manipulate the
  77.         listview in any way.  If you set DCLV_CURRENT to -1 at any point,
  78.         be prepared to properly handle -1 as a returned value when you
  79.         get(DCLV_CURRENT).
  80.     DCLV_DISABLED                     [ISG]
  81.         Whether this gadget is disabled.  Works under v39+ only, and is
  82.         minimal at best (the listview is disabled, but the attached prop
  83.         gadget will still scroll the list).  (Default: FALSE)
  84.     DCLV_TOP                          [ISG]
  85.         Sets which item in the list is to be diplayed at the top of the
  86.         listview, without necessarily being currently selected.
  87.     DCLV_CLICK                        [..G]
  88.         This will be set to TRUE when an item from the listview has been
  89.         double-clicked.
  90.  
  91. Exceptions:
  92.  
  93.     "dclv" will be raised by gtrender() if the gadget can't be created.
  94.     "util" will be raised by dclistview() if utility.library isn't open.
  95.  
  96. History:
  97.  
  98. 13-Jul-97  First release
  99.  
  100. 19-Aug-97  Second release
  101.            - removed a v39-only function that pretty much squashed the plugin
  102.              under v37.
  103.  
  104. 19-Jan-98  Third release
  105.            - rewritten in a style similar to the EasyPLUGINs Style Guide;
  106.            - replaced long list of constructor arguments with a taglist;
  107.            - replaced specific set#?/get#? functions with multi-purpose ones,
  108.              allowing many more attributes to be set/get with minimum effort,
  109.              and allowing the entire dclistview object to be made private;
  110.            - now checks if window and gadget exist (i.e., not iconified) before
  111.              updating attributes;
  112.            - simplified node-counter function;
  113.